home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / MATH / MATHLIB / MATHLIB.DOC next >
Text File  |  1993-06-21  |  16KB  |  296 lines
  1.                     Math Library (MATHLIB) for Turbo Pascal
  2.                    Copyright (c) 1991,1993 Waldman Sidelines
  3.        Harness the Power of the Advanced Coprocessors in Your Programs!
  4.                                        
  5.                                Waldman Sidelines
  6.                                 Cye H. Waldman
  7.                             Post Office Box 231157
  8.                            Encinitas, CA  92023-1157
  9.                   Technical Support on CompuServe: 72245,1337
  10.                                        
  11.                                  INTRODUCTION
  12.                                        
  13. Turbo Pascal is robbing you of performance in two important ways.  First, all 
  14. transcendental math functions (trig and exponential) are coded for the 8087 
  15. coprocessor and don't take advantage of the advanced instruction set in the 
  16. 80x87 or 80486.  Second, if you use a memory manager (386MAX, HIMEM, etc.) then
  17. your math performance is being compromised.  Fortunately, MATHLIB fixes these 
  18. problems.  MATHLIB is designed specifically for use with the 80x87 coprocessor. 
  19. MATHLIB replaces the intrinsic Pascal math functions and adds twenty-three new 
  20. ones as well (including the full C/C++ set).  It taps the full power of your 
  21. 80x87 coprocessor and alleviates the memory manager bottleneck.
  22.  
  23. MATHLIB should be of particular interest to those performing numerically 
  24. intensive computations such as scientific and engineering calculations and 
  25. graphics applications which require coordinate transformations using 
  26. trigonometric relations.
  27.  
  28. This program is a shareware product.  You may distribute the original shareware 
  29. disk (not including the source code) to your friends for evaluation.  If you 
  30. use this program you are expected to register it with Waldman Sidelines.  
  31.  
  32. Your registration fee entitles you to use this software on a single computer 
  33. and to make as many copies of this software as you wish for your own backup 
  34. purposes.  Site licenses are available; call for details.  You may not use
  35. MATHLIB in a commercial product; a separate license agreement must be 
  36. established with Waldman Sidelines.
  37.  
  38. Upon receipt of your registration you will receive a disk with the Pascal 
  39. source and the assembled object code required to compile the unit.  (Contact 
  40. the author regarding availability of the assembly language source code.)  In 
  41. addition, you will receive notifications of future software updates.
  42.  
  43.                               LIMIT OF LIABILITY
  44.                                
  45. MATHLIB is distributed as-is. The author disclaims all warranties expressed or 
  46. implied.  The author will assume no liability for damages either from direct 
  47. use of this product or as a consequence of the use of this product.
  48.  
  49.                                    COPYRIGHT
  50.                                        
  51. MATHLIB is copyrighted with all rights reserved to Waldman Sidelines.
  52.                                        
  53.                                   TRADEMARKS
  54.  
  55. Turbo Pascal is a registered trademark of Borland International, Inc.
  56. 386MAX is a registered trademark of Qualitas, Inc.
  57. NetRoom is a trademark of Helix Software Company, Inc.
  58. Microsoft and MS-DOS are registered trademarks of Microsoft, Inc.
  59.  
  60. MATHLIB Documentation                                                   Page 1
  61.                                   DESCRIPTION
  62.  
  63. Two Turbo Pascal 7.0 units (TPU files) are provided with this software.  The
  64. MATHLIB unit provides faster floating point calculation by directly accessing 
  65. the advanced instruction set of the 80x87 coprocessors.  (These are not 
  66. accessible to math functions compiled under Turbo Pascal which is limited to 
  67. the 8087 instruction set.)  The software automatically detects the coprocessor 
  68. and provides the optimal code.  The unit is in file MATHLIB.TPU.  It contains 
  69. replacements for the intrinsic system functions (i.e., ARCTAN, COS, EXP, LN, 
  70. SIN) as well as twenty-three additional functions.  All functions are coded in 
  71. assembly language.  The TrigStuff unit (in TRIGSTUF.PAS and TRIGSTUF.TPU) 
  72. contains the Pascal source code for the twenty-three new functions.  This set
  73. of functions includes all those in the standard C/C++ math library.  Some
  74. of the functions have different names than in the C/C++ library, however.
  75.  
  76. The library is intended for users familiar with Turbo Pascal and the use of 
  77. units.  Those not familiar with units should refer to the Turbo Pascal manuals.
  78.  
  79.                                 NOTES ON USAGE
  80.  
  81. 1.  Functions supported by the library (in alphabetical order):
  82.  
  83.     FUNCTION ACOSH(x: DOUBLE):DOUBLE;           { inverse hyperbolic cosine   }
  84.     FUNCTION ArcCOS(x: DOUBLE):DOUBLE;          { inverse cosine function     }
  85.     FUNCTION ArcSIN(x: DOUBLE):DOUBLE;          { inverse sine function       }
  86.     FUNCTION ARCTAN(x: DOUBLE):DOUBLE;          { inverse tangent function    }
  87.     FUNCTION ArcTangent(x,y: DOUBLE):DOUBLE;    { optional inverse tan func   }
  88.     { returns arctan(y/x) in the proper quadrant, e.g., 0-360 degrees         }
  89.     FUNCTION ASINH(x: DOUBLE):DOUBLE;           { inverse hyperbolic sine     }
  90.     FUNCTION ATANH(x: DOUBLE):DOUBLE;           { inverse hyperbolic tangent  }
  91.     FUNCTION CEIL(x: DOUBLE);                   { smallest integer > x        }
  92.     FUNCTION COS(x:DOUBLE):DOUBLE;              { cosine function             }
  93.     FUNCTION COSH(x:DOUBLE):DOUBLE;             { hyperbolic cosine function  }
  94.     FUNCTION EXP(x:DOUBLE):DOUBLE;              { exponential fn, e^x         }
  95.     FUNCTION FLOOR(x: DOUBLE);                  { largest integer < x         }
  96.     FUNCTION FMOD(x,y:DOUBLE):DOUBLE;           { x modulo y                  }
  97.     { returns remainder f, where x = a*y + f for some integer a & f in [0,y)  }
  98.     FUNCTION FREXP(x: DOUBLE; VAR n INTEGER);DOUBLE;
  99.     { returns m for which x = m*2^n with m in [0.5,1)                         }
  100.     FUNCTION Expo(x,y:DOUBLE):DOUBLE;           { exponential fn, x^y         }
  101.     FUNCTION HYPOT(x,y: DOUBLE):DOUBLE;         { SQRT(SQR(x)+SQR(y))         }
  102.     FUNCTION LDEXP(x: DOUBLE; n INTEGER);DOUBLE;{ returns x * 2 ^ n           }
  103.     FUNCTION LN(x:DOUBLE):DOUBLE;               { natural logarithm function  }
  104.     FUNCTION LOG(x:DOUBLE):DOUBLE;              { common logarithm function   }
  105.     FUNCTION MODF(x: DOUBLE; VAR y DOUBLE);DOUBLE;
  106.     { breaks x into integer and fraction, returns fraction puts integer in y  }
  107.     FUNCTION POLY(x:DOUBLE; n:INTEGER; VAR degree):DOUBLE;
  108.     { returns y = c0 + c1*x + c2*x^2 + ... + cn*x^n; n = polynomial order     }
  109.     FUNCTION SIN(x:DOUBLE):DOUBLE;              { sine function               }
  110.     PROCEDURE SINCOS(x:DOUBLE; VAR y,z:DOUBLE); { sine/cosine procedure       }
  111.     { returns both sine and cosine; y = SIN(x), z = COS(x)                    }
  112.     FUNCTION SINH(x:DOUBLE):DOUBLE;             { hyperbolic sine function    }
  113.     FUNCTION TAN(x:DOUBLE):DOUBLE;              { tangent function            }
  114.     FUNCTION TANH(x:DOUBLE):DOUBLE;             { hyperbolic tangent function }
  115.     FUNCTION Ten2TheX(x:DOUBLE):DOUBLE;         { exponential fn, 10^x        }
  116.     FUNCTION Two2TheX(x:DOUBLE):DOUBLE;         { exponential fn, 2^x         }
  117.  
  118.  
  119. MATHLIB Documentation                                                   Page 2
  120. 2.  The library is valid only for type DOUBLE.  (The author has found type
  121.     DOUBLE to be faster than type REAL.)  Contact Waldman Sidelines concerning
  122.     other types.
  123.  
  124. 3.  The library is compiled in Turbo Pascal 7.0 with the /v option.  Object
  125.     code is compiled with TASM 3.2 in the IDEAL mode with the TPASCAL MODEL.
  126.  
  127. 4.  Standard USES convention; i.e., USES MathLib.
  128.  
  129. 5.  Install the TPU file in a directory where Turbo Pascal will find it and
  130.     use it in the normal way.  E.g., can be USED in other units.
  131.  
  132. 6.  This advanced library automatically supersedes the intrinsic math functions.
  133.     No explicit action is required on the part of the user.
  134.  
  135. 7.  Automatic hardware recognition: the same library will work for '287 and
  136.     '387 machines without recompiling.
  137.  
  138. 8.  This library has been in use for about four years in mathematical models
  139.     of physical systems developed by the author.  Speed increases of up to
  140.     40% have been observed in computationally intensive programs.
  141.  
  142. 9.  Until you become familiar with these programs it would be prudent to
  143.     verify that they give the results you expect by comparing output from the
  144.     same program compiled with the system and MATHLIB units.
  145.  
  146. 10. Registered users will receive a registration number and all Pascal source
  147.     code and assembled object code.  The source and object codes will allow 
  148.     compilation to past and future versions of Turbo Pascal without an 
  149.     assembler.  The registered version does not contain the initialization 
  150.     shareware information screen.
  151.  
  152. 11. Technical support is available on CompuServe at ID 72245,1337.
  153.  
  154.                                 CUSTOM VERSIONS
  155.  
  156. Custom versions of the MATHLIB unit can be developed for your organization.  
  157. For example, renaming the functions so that the library can be used 
  158. concurrently with the system libraries, or addition of new functions hand coded 
  159. in assembly language.  Please contact Waldman Sidelines for a quotation.
  160.  
  161.                           PERFORMANCE CONSIDERATIONS
  162.     
  163. The author has run numerous time trials with the library with various systems 
  164. ('286 through '486) and with and without memory managers installed.  The exact 
  165. performance increase is sensitive to these two parameters (i.e., coprocessor 
  166. and memory manager).  However, there is always a substantial performance 
  167. increase.  If you have a '387 (or '486) you will notice a very strong impact of 
  168. using the built-in TAN, SIN, and COS functions and SINCOS procedure in the
  169. 80387 instruction set.  Also, good advantage is taken of the redefinition of 
  170. the ARCTAN and exponentiation instructions as well.  The library was tested 
  171. extensively for accuracy; a program was developed which drew random arguments 
  172. and compared the results of the new library with the standard Pascal results.
  173.  
  174.  
  175.  
  176.  
  177.  
  178. MATHLIB Documentation                                                   Page 3
  179. A timing program has been included to test on your own system.  Try it with and 
  180. without your memory manager installed.  I've also provided the source code, 
  181. but, sorry, I can't give you the timing routine because it's a TurboPower 
  182. product.  I've also provided the Savage benchmark which I find to be 2.77 times 
  183. faster the standard Pascal result (with 386MAX on a 486/33).  The effect of 
  184. the memory manager is discussed below.
  185.  
  186. In the course of developing the timing benchmarks it was discovered that the 
  187. presence of a memory manager had a rather significant effect on the 
  188. performance of the intrinsic math functions in Turbo Pascal.  The results with 
  189. a memory manager were about 25-40% slower.  We found this to be true for three 
  190. memory managers we tested (i.e., 386MAX, NetRoom, and Microsoft MS-DOS 5.0 
  191. HIMEM/EMM386).  We reported this anomalous behavior to Borland who were able 
  192. to duplicate this odd result with QEMM as well.  Also, there was a great deal 
  193. of variability in the results with the memory managers we tested.  In our 
  194. tests, 386MAX was the fastest and Microsoft MS-DOS 5.0 HIMEM/EMM386 was the 
  195. slowest.  The question arises as to whether the problem is with Turbo Pascal 
  196. or with the memory managers.  To answer that question we developed a similar 
  197. performance test of the intrinsic math functions in Microsoft FORTRAN.  The 
  198. memory manager (386MAX, in this case) only slowed down the operations by about 
  199. 2%, which is about what we would expect.  This seems to suggest some 
  200. deficiency in Turbo Pascal, but we have no hard core information as yet.  The 
  201. good news is that the mathematics functions in the library provided herein
  202. appears to be virtually unaffected by the memory mangers.  Please share your
  203. own observations with us.
  204.         
  205. The following table shows the performance increase with MATHLIB realized on
  206. a Club American '486/33 with 386MAX installed.
  207.  
  208.                             Speed                       Speed
  209.                 Function    Ratio           Function    Ratio
  210.                 --------    -----           --------    -----
  211.                 LN           1.88           CEIL         2.19
  212.                 LOG          2.40           FLOOR        2.64
  213.                 Two2TheX     3.92           FMOD         2.51
  214.                 EXP          2.15           FREXP       15.66
  215.                 Ten2TheX     4.34           HYPOT        1.53
  216.                 Expo         2.42           LDEXP       11.38
  217.                 TAN          5.51           MODF         1.77
  218.                 SIN          2.25           POLY         2.32
  219.                 COS          2.25           COSH         2.26
  220.                 SINCOS       4.04           SINH         2.26
  221.                 ARCTAN       1.93           TANH         2.27
  222.                 ArcTangent   2.48           ACOSH        2.02
  223.                 ArcSIN       2.09           ASINH        2.01
  224.                 ArcCOS       2.87           ATANH        1.90
  225.  
  226. Demonstration of the POLY function is given in MATHTIME.PAS and TRIGSTUF.PAS
  227. which were used to produce the above results.  Source code for these functions
  228. is provided herewith.  The latter file contains the Pascal source for all the
  229. new functions.  Of course, these are coded in assembler in the MATHLIB unit.
  230.  
  231. If MATHLIB doesn't meet your floating point calculation needs please let us
  232. know why.  Thanks.
  233.  
  234.  
  235.  
  236.  
  237. MATHLIB Documentation                                                   Page 4
  238.                 INVOICE & REGISTRATION FOR MATHLIB VERSION 2.0
  239.  
  240.         Please remit to:            Waldman Sidelines
  241.                                     Cye H. Waldman
  242.                                     P.O. Box 231157
  243.                                     Encinitas, CA  92023-1157
  244.  
  245.                               LIMIT OF LIABILITY
  246.  
  247.      The MATHLIB library (MATHLIB.TPU) is distributed as-is.  The author 
  248.      disclaims all warranties, expressed or implied.  The author will 
  249.      assume no liability for damages either from the direct use of this 
  250.      product or as a consequence of the use of this product.
  251.  
  252.      Please register one copy of MATHLIB for each user at your site.
  253.  
  254.         MATHLIB Registration     Qty. _____ @ $25.00 ea.     = ____________
  255.  
  256.         Calif. Residents Add 7.75% Sales Tax                 + ____________
  257.  
  258.                                                 Total Payment: ____________
  259.  
  260.      Registered users will receive a disk with the Pascal source code and 
  261.      assembled object code.  Registered users will be notified of new 
  262.      updates.  Suggestions for extensions of the library are welcome as 
  263.      well as requests for developments of similar libraries for other 
  264.      languages.  Comments are also welcome from those who elect not to 
  265.      register.  Thank you for using MATHLIB.
  266.         
  267.         Name:  ____________________________________________________________
  268.    
  269.         Company:  _________________________________________________________
  270.  
  271.         Address:  _________________________________________________________
  272.  
  273.         Day Phone:  _______________________  Eve:  ________________________
  274.  
  275.         Preferred Technical Support (Tel, CompuServe, etc.) _______________
  276.  
  277.      
  278.      COMMENTS AND SUGGESTIONS
  279.  
  280.      ______________________________________________________________________
  281.  
  282.      ______________________________________________________________________
  283.  
  284.      ______________________________________________________________________
  285.  
  286.      ______________________________________________________________________
  287.  
  288.      ______________________________________________________________________
  289.  
  290.      ______________________________________________________________________
  291.  
  292.      ______________________________________________________________________
  293.  
  294.      ______________________________________________________________________
  295.  
  296.      ______________________________________________________________________